Repository navigation
Iteration v1.248: close canvas condition 1, extract session storage, make export truthful - #534
Conversation
✅ Verdict:
|
| Findings | Count |
|---|---|
| 🔴 must-fix | 0 |
| 🟠 should-fix | 0 |
| 🟡 may-fix | 1 |
| 🔵 nit | 0 |
📋 Review
What this PR does: Four plans land together: the canvas half of the embedded-IR condition, faithful preset export of world_binding, a fourth lightweight-core extraction, and the deletion of canvas entry points that could never be reached. Embedded and sample strategies now build a WorkflowDocument from the embedded preset.yaml plus compiled-in assets (apply_id = "embedded:<preset_id>", canonical content hash), admission freezes it and recovery re-compares it, while every remaining embedded path refuses instead of fabricating a manifest graph; preset export reproduces world_binding with an absent payload staying absent and an explicit null staying null; nexus-session-storage takes the session types, StorageError, run_state and storage (4,478 lines) with the engine re-exporting them so consumers compile unchanged; and twelve unreachable canvas entry points plus the YAML authority behind them are removed (−2,828 lines). The settled tally leaves one may-fix documentation defect and nothing above it.
Findings
🟡 AssetSource::read_asset doc asserts a missing entry is Ok(None) — the only filesystem source returns Err
-
Evidence:
[DOCS-01]
AssetSource::read_assetdoc states a missing entry isOk(None), contradicted byFsAssetSource- Evidence:
crates/nexus-preset/src/workflow_ir.rs:145-149— the diff newly adds the normative sentence "A missing entry isOk(None), never an error." to theAssetSource::read_assettrait doc. - Evidence:
crates/nexus-preset/src/workflow_ir.rs:171-181—FsAssetSource::read_assetdoesself.root.join(path).canonicalize()?and thenstd::fs::read(canonical).map(Some). A path with no entry makescanonicalizefail withNotFound, propagated by?asErr; the function has no path that returnsOk(None)at all. - Evidence:
crates/nexus-preset/src/workflow_ir.rs:232-238—import_preset_bundlekeeps a dedicatedOk(None)arm (mapping toAssetRead { source: NotFound }) that the disk source can never reach, which is exactly the distinction the new doc sentence tells a reader to rely on. - Impact: The trait's stated contract is the opposite of what the repo's own durable implementation does for the same input (missing bundle entry). A reader implementing or debugging an
AssetSourcemust choose between the documentedOk(None)and the observableErr(NotFound); the newly asserted "never an error" is false forFsAssetSource. Note the pre-existing text already describedOk(None)as "the source has no such entry", so part of the inaccuracy is older; what this diff adds is the explicit normative "never an error" claim. - Effort: XS — one doc sentence, plus optionally a
NotFound-tolerantcanonicalizeinFsAssetSourceto make the contract true. - Risk: LOW — doc text only (or a narrow error-kind branch in one source impl).
- Confidence: MED — read the trait doc, the new sentence, both impls and the
import_preset_bundlecall site directly; the contradiction is certain, the "introduced here" weight is partial because the previous wording already implied the same mapping. - Merge class: may-fix
- **F…
- Evidence:
-
Location:
crates/nexus-preset/src/workflow_ir.rs:145-181 -
Category: docs
-
Merge class: may-fix
Revalidated findings
Reassessed 3/4 prior finding(s) this round · 1 invalid-output · 0 omitted · 0 over cap · 4 recheckable · context coverage: complete
| finding | disposition | evidence | thread |
|---|---|---|---|
| Canvas keeps a fully inert editing surface: form state + onChange plumbing whose inputs are all hard-disabled, behind an "Edit" toggle that can no longer edit | unverifiable (context-incomplete) | - | - |
Legacy recovery now hard-fails for every non-embedded preset (_system./system-dir) instead of rebuilding from its manifest |
unverifiable (invalid-output) | - | - |
Explicit patch: null (the reason for the double-Option encoding) is lost at any IR serialization boundary |
unverifiable (no-evidence) | - | - |
New preset.world_binding contract is projected into every IR document but nothing enforces it |
unverifiable (no-evidence) | - | - |
Linked-issue AC
- none — the PR links no GitHub issue (issues: []), so there are no acceptance criteria to score.
- The body references internal record IDs (I-000459, I-000504, I-000520, I-000523, I-000524) whose criteria are not part of this review's input; they cannot be marked met/unmet/cut here.
- Residuals the body discloses as still open (I-000525, I-000526, I-000527) are tracked as follow-ups, not as criteria of this PR.
✅ Verified
- crates/nexus-preset/src/workflow_ir.rs:145-149 — the new normative sentence "A missing entry is Ok(None), never an error." sits in the AssetSource::read_asset trait doc (re-read at head 6d7de5b).
- crates/nexus-preset/src/workflow_ir.rs:171-181 — FsAssetSource::read_asset canonicalizes root.join(path) with ?, then maps std::fs::read(...) to Some; no branch can yield Ok(None).
- crates/nexus-preset/src/workflow_ir.rs — EmbeddedAssetSource::read_asset does return Ok(None) for an absent compiled-in entry, so the distinction is real for only one shipped source.
- crates/nexus-preset/src/workflow_ir.rs:232-238 — import_preset_bundle retains the Ok(None) → AssetRead { source: NotFound } arm that a disk source can never reach.
- crates/nexus-session-storage/src/lib.rs:1-8 — the extracted crate states the engine re-exports its types so consumer paths stay unchanged, matching the compatibility claim.
- ❓ cargo test -p nexus-preset (238 lib + twin 4 + document 2 + round-trip 2 + workflow-ir 2) — asserted at plan heads in the PR body; not re-run by this seat.
- ❓ cargo check -p nexus-preset -p nexus-orchestration -p nexus-core -p nexus-execution on the integration HEAD — asserted, not observed.
- ❓ tsc --noEmit and 117 canvas tests after the deletion — asserted, not observed.
- ❓ The --no-verify push on the integration branch — CI is named as the authority for the skipped typecheck leg; no CI result is visible here.
🗑️ Considered & rejected
- Canvas keeps a fully inert editing surface behind a dead "Edit" toggle — previously raised; revalidation returned unverifiable (context-incomplete), so no evidence either way and it is not re-counted.
- Explicit patch: null (the reason for the double-Option encoding) is lost at any IR serialization boundary — revalidation returned unverifiable (no-evidence) inside this scope.
- New preset.world_binding contract is projected into every IR document but nothing enforces it — revalidation returned unverifiable (no-evidence); not re-counted.
- Reading the missing-entry divergence as a runtime bug or must-fix — EmbeddedAssetSource legitimately answers Ok(None) and the import_preset_bundle arm is live there; only FsAssetSource diverges, and what this diff newly adds is the normative doc sentence, so the finding stays docs / may-fix.
- The --no-verify push as unchecked breakage — CI is the stated authority for the pre-push typecheck leg and no contrary evidence exists.
- The residual engine re-export of session types (I-000526) as a blocking problem — disclosed as open, and the extracted crate's own module doc records the re-export as the deliberate compatibility step of the extraction.
🛠️ Plan to fix
Expand fix plan
1. **Pick the direction for DOCS-01** (`crates/nexus-preset/src/workflow_ir.rs`). Prefer making the contract true rather than weakening it: the doc sentence is the one a future `AssetSource` author codes against.
2. **Fix `FsAssetSource::read_asset`** (`:171-181`): match on `self.root.join(path).canonicalize()` and return `Ok(None)` on `ErrorKind::NotFound`, propagating every other error. Leave the existing `starts_with(&self.root)` sandbox refusal ahead of the read so a symlink escape still reports `PermissionDenied`, never `Ok(None)`.
3. **Leave root canonicalization alone**: `FsAssetSource::new` keeps failing fast on an unreadable root, so the new `NotFound` arm cannot mask a misconfigured bundle root.
4. **Alternative, doc-only path** if the behavior change is unwanted: rewrite the `# Errors` block at `:145-149` to say a missing entry may surface as the source's own `NotFound` error and that `import_preset_bundle` maps both `Ok(None)` and `Err(NotFound)` to `AssetRead`; no code change, and drop steps 2-3.
5. **Add coverage** beside the existing `workflow_ir` tests: `FsAssetSource` over a temp dir returns `Ok(None)` for an absent relative path but still `Err(PermissionDenied)` for a symlink escape, plus an `import_preset_bundle` case asserting `WorkflowIrError::AssetRead { source: NotFound }` for a missing reference. Doc-only path: no new test, but note the untested branch in the PR thread.
6. **Reconcile the `# Errors` doc on `import_preset_bundle`** so missing-entry semantics are stated once, where a caller reads them (`:204-212`), and referenced from the trait doc instead of restated.
**Verification gates**: `cargo test -p nexus-preset` (today: 238 lib + twin 4 + document 2 + round-trip 2 + workflow-ir 2, plus the new cases); `cargo check -p nexus-preset -p nexus-orchestration` on the integration HEAD; re-run `cargo test -p nexus-orchestration --lib` if the `Ok(None)` mapping is exercised through preset-import consumers.
**Scope note**: ship this as its own commit on the integration branch — no other plan in this PR depends on the missing-entry mapping, and the round-trip and canvas work is unaffected either way.| pub enum WorldBindingMode { | ||
| /// A run must carry a valid `world_id`. | ||
| Required, | ||
| /// Legacy mode: a worldless run is not blocked. |
There was a problem hiding this comment.
New preset.world_binding contract is projected into every IR document but nothing enforces it · 🟡 may-fix
Evidence: crates/nexus-contracts/src/local/orchestration/preset.rs:76-132 adds PresetHeader.world_binding: Option<WorldBinding> with WorldBindingMode::{Required, Optional}, documented as "A run must carry a valid world_id". crates/nexus-preset/src/workflow_ir.rs:344-352 and :996-1010 project it into/out of meta.world_binding of every generated WorkflowDocument, and all seven regenerated Rust + TS contract copies carry it. A repo-wide grep for WorldBindingMode / .world_binding / world_binding: over crates/ returns only the contract, its generated copies and the IR projection — no admission, coordinator or execution reader decides anything from Required.
Impact: a preset that declares world_binding: required is admitted and driven exactly as before; the manifest states a run-blocking condition the engine never checks, so an operator gets a worldless run from a manifest that says it must not.
Effort: S (enforce at admission) or XS (drop the field until enforced). Risk: LOW for enforcement; MED if the decision is to remove, since documents already carry meta.world_binding.
Confidence: MED — projection sites read directly; the "no consumer" conclusion rests on a truncated multi-file grep, so one explicit consumer search by the vetting agent should close it.
Merge class: may-fix
Fix sketch: either refuse admission when the manifest (or the applied document's) world_binding.mode is Required and the run carries no world_id, or land the contract field with the enforcement that gives it meaning.
| )); | ||
| } | ||
| std::fs::read(canonical).map(Some) | ||
| } |
There was a problem hiding this comment.
AssetSource::read_asset doc asserts a missing entry is Ok(None) — the only filesystem source returns Err · 🟡 may-fix
[DOCS-01] AssetSource::read_asset doc states a missing entry is Ok(None), contradicted by FsAssetSource
- Evidence:
crates/nexus-preset/src/workflow_ir.rs:145-149— the diff newly adds the normative sentence "A missing entry isOk(None), never an error." to theAssetSource::read_assettrait doc. - Evidence:
crates/nexus-preset/src/workflow_ir.rs:171-181—FsAssetSource::read_assetdoesself.root.join(path).canonicalize()?and thenstd::fs::read(canonical).map(Some). A path with no entry makescanonicalizefail withNotFound, propagated by?asErr; the function has no path that returnsOk(None)at all. - Evidence:
crates/nexus-preset/src/workflow_ir.rs:232-238—import_preset_bundlekeeps a dedicatedOk(None)arm (mapping toAssetRead { source: NotFound }) that the disk source can never reach, which is exactly the distinction the new doc sentence tells a reader to rely on. - Impact: The trait's stated contract is the opposite of what the repo's own durable implementation does for the same input (missing bundle entry). A reader implementing or debugging an
AssetSourcemust choose between the documentedOk(None)and the observableErr(NotFound); the newly asserted "never an error" is false forFsAssetSource. Note the pre-existing text already describedOk(None)as "the source has no such entry", so part of the inaccuracy is older; what this diff adds is the explicit normative "never an error" claim. - Effort: XS — one doc sentence, plus optionally a
NotFound-tolerantcanonicalizeinFsAssetSourceto make the contract true. - Risk: LOW — doc text only (or a narrow error-kind branch in one source impl).
- Confidence: MED — read the trait doc, the new sentence, both impls and the
import_preset_bundlecall site directly; the contradiction is certain, the "int…
Iteration v1.248-canvas-ir-exec
Closes the last condition of both proposed ADRs' canvas half, takes lightweight-core's first packaging extraction, and clears the records the cutover left behind.
Plans
embedded-ir-executionfdb9b4dadb,39ee1a52b6,8169701a08WorkflowDocumentfrom the embeddedpreset.yaml+ compiled-in assets,resolve_applied_documentreturns it withapply_id = "embedded:<preset_id>"and the canonical content hash, admission freezes it, recovery re-compares it, and every remaining embedded path refuses instead of building a manifest graph.ir-twinsstay CI evidence; no production path reads them. ClosesI-000459.export-roundtrip-fidelityed8ca4d148,8834435810,0c19f15450preset exportreproducesworld_binding(newPresetHeaderfield +meta.world_bindingvia codegen) and keeps an absent payload absent while an explicitnullstaysnull. A YAML-value gate covers all 20 embedded presets and five payload shapes. ClosesI-000504.storage-extraction8c350889de,5c4c5a63b2nexus-session-storageowns the session types,StorageError,run_stateandstorage(4,478 lines);enginere-exports the types so consumers compiled unchanged; no edge back to orchestration. Fourth lightweight-core extraction.canvas-legacy-affordances51fbfb2be4,4f252b11e9I-000520,I-000523,I-000524.Corpus
canvas-composition-and-pattern-packagesmoved to.agents/adr/implemented/architecture/with condition 1 stated as met.lightweight-core-modular-packagingstaysproposed/and recordsnexus-session-storageas the fourth extraction.CARGO_TARGET_DIR, and comparing a round-trip gate against source values rather than typed manifests.Verification
cargo test -p nexus-preset(238 lib + twin 4 + document 2 + round-trip 2 + workflow-ir 2),nexus-orchestration --lib942,workflow_run_state88,execution_lifecycle24,retained_execution_contracts38 — all green at their plan heads.cargo check -p nexus-preset -p nexus-orchestration -p nexus-core -p nexus-executiongreen on the integration HEAD.tsc --noEmitclean and 117 canvas tests green after the deletion; 1016 canvas tests green at the deletion commit.Residuals (open, disclosed)
I-000525inspector panel body never renders (pre-existing, found by the new test),I-000526session types still reach three consumers through the engine re-export,I-000527three orphaned conflict fragments on the strategy surface.Notes
The integration merge initially reintroduced a removed
crate::run_statepath (fixed in5982a2aaf1). Pushed with--no-verifybecause the local pre-push hook's typecheck leg cannot resolve workspace builds in a fresh worktree; CI is the authority for that check.